home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / intrvews / 31.lha / README
Text File  |  1992-06-05  |  14KB  |  320 lines

  1.  
  2.         README for InterViews 3.1
  3.  
  4.  
  5. The iv subdirectory in this directory contains the InterViews 3.1
  6. distribution from Stanford University and Silicon Graphics.
  7. You should read the release notes in iv/src/man/refman/refman.PS
  8. for information about differences between 3.0 and 3.1.  You should
  9. read the rest of this file for information about how to build,
  10. install, and use InterViews.
  11.  
  12. If you have a bug report, please send it to
  13.  
  14.     interviews-bugs@interviews.stanford.edu
  15.  
  16. If you have any questions or problems, please post them in the USENET
  17. newsgroup
  18.  
  19.     comp.windows.interviews
  20.  
  21. If you do not have access to news and you wish to be on the InterViews
  22. mailing list which is gatewayed with comp.windows.interviews, send a
  23. request to
  24.  
  25.     interviews-requests@interviews.stanford.edu
  26.  
  27. The mailing list alias is
  28.  
  29.     interviews@interviews.stanford.edu
  30.  
  31. Please post to only the newsgroup or only the mailing list but not
  32. both since whatever you post in one will appear in the other too.
  33.  
  34.  
  35. * What else to get
  36.  
  37.  
  38. You should have gotten a C++ compiler which accepts revision 2.0 or
  39. later of the language.  You should have installed the X11R4 or
  40. X11R5 distribution from MIT.  If you use a vendor's X11 product,
  41. the product should be based on R4 or later and the product
  42. should include imake, makedepend, and the config files.
  43.  
  44. If imake and makedepend are not in the same place where the other X11
  45. binaries are or anywhere else on your system, you can get the sources
  46. for imake and makedepend from the X11R4 distribution at several public
  47. ftp archives (such as expo.lcs.mit.edu).  The X11R4 distribution also
  48. contains platform-specific configuration files (*.cf) which you must
  49. put in /usr/lib/X11/config or a similar place before building
  50. InterViews.
  51.  
  52.  
  53. * What to do before building InterViews
  54.  
  55.  
  56. You should check that you have about 50Mb of free space before you
  57. unpack the 3.1 tar file.  If you have SunOS shared libraries, you can
  58. get by with about 35Mb.  The InterViews source tree itself occupies
  59. only 8Mb, but saying "make World" will add 17Mb to iv and saying "make
  60. install" will add another 18Mb.
  61.  
  62. You should read and edit iv/src/config/InterViews/local.def before
  63. building InterViews.  This file is the place to set parameters which
  64. may need to be changed for your site.  To find out which parameters
  65. you can set, read params.def in the same directory.
  66.  
  67. For example, you might add the lines
  68.  
  69.     #undef CCDriver
  70.     #define CCDriver /usr/CC/sun4/CC
  71.     #undef DependCCFlags
  72.     #define DependCCFlags $(CCDEFINES) $(CCINCLUDES) -I/usr/CC/incl
  73.     #undef SharedCCFlags
  74.     #define SharedCCFlags -PIC
  75.  
  76. to local.def if you use Sun C++ 2.0.  Sun C++ 2.0 will not be able
  77. to build libIV.so.3.0 unless you use -PIC instead of -pic.
  78.  
  79. You must decide whether to change the definition of InstalledRoot in
  80. local.def before building InterViews since the name will be compiled
  81. into InterViews applications.  For example, the application "doc" will
  82. expect to get its menus from /interviews/lib/all/app-defaults/Doc at
  83. startup unless you set InstalledRoot to something else before building
  84. InterViews.
  85.  
  86. Other parameters you may also have to set are where to find the X11
  87. config files, includes, and libraries.  If the X11 config files are
  88. not in /usr/lib/X11/config, the X11 includes are not in /usr/include,
  89. or the X11 libraries are not in /lib, /usr/lib, or /usr/local/lib,
  90. then you should specify their actual locations in local.def.  For
  91. example, you might add the lines
  92.  
  93.     #undef XConfigDir
  94.     #define XConfigDir /usr/X11R5/lib/X11/config
  95.     #undef XIncDir
  96.     #define XIncDir /usr/X11R5/include
  97.     #undef XLibDir
  98.     #define XLibDir /usr/X11R5/lib
  99.  
  100. if you are using X11R5 and it is installed in /usr/X11R5.  You will
  101. also have to override XCONFIGDIR when saying "make World"; see
  102. below.
  103.  
  104. You should read the X11 platform-specific .cf file that will be used
  105. when you build InterViews.  It probably will set a few InterViews
  106. parameters like extra compiler flags, extra defines, or extra
  107. libraries so you should check that all of these extra flags work with
  108. your C++ compiler as well as with your C compiler.  If your C++
  109. compiler will not accept some of them or it needs some additional
  110. flags, you can set the affected InterViews parameters in the
  111. corresponding iv-*.cf file before xparams.cf sets them.  See iv-sgi.cf
  112. and iv-ultrix.cf for examples.  The iv-*.cf file is the only other
  113. file besides local.def which you should ever need to change.  (If you
  114. have to change this file, please send us the changes so we can
  115. incorporate them in the next release.)
  116.  
  117.  
  118. * How to build InterViews
  119.  
  120.  
  121. After you set any necessary parameters in local.def, you can build
  122. InterViews with the following commands (but read the rest of this
  123. section first!):
  124.  
  125.     cd iv
  126.     setenv CPU `make CPU`
  127.     make World XCONFIGDIR=<actual location of X11 config files>
  128.  
  129. As the first command shows, you should be in the iv directory (below
  130. this README) before starting to build InterViews.  
  131.  
  132. The second command assigns the name of your machine's architecture to
  133. the environment variable CPU.  Saying "make CPU" by itself will print
  134. the name that you should assign to CPU (MIPSEL, SUN4, etc.).  If you
  135. do not set CPU, the Makefiles will not be able to create the
  136. appropriate subdirectories in which to put the object code files and
  137. you will not be able to build InterViews.
  138.  
  139. The third command builds everything for you.  If the X11 config files
  140. are not in /usr/lib/X11/config, you must override XCONFIGDIR on the
  141. command line as well as set XConfigDir in local.def or "make World"
  142. will not work correctly.
  143.  
  144. You may want to redirect the output of "make World" to a file and
  145. inspect it later since the build will take more than two hours to
  146. complete on a system with the performance of a DECstation 3100 or
  147. SPARCstation 1.
  148.  
  149. Once the build concludes, you can find errors in the output quickly by
  150. searching for the character ':' (unfortunately, this will not work
  151. very well if your C++ compiler driver prints verbose output showing
  152. the execution of each phase).
  153.  
  154.  
  155. * How to install InterViews
  156.  
  157.  
  158. To install InterViews, say
  159.  
  160.     make install
  161.  
  162. in the same directory where you said "make World".  This command will
  163. create a new subdirectory called installed and install inside this
  164. directory everything that you will need to use InterViews.  Since
  165. "make install" will not try to install anything outside of
  166. iv/installed, you can say it without having to become the superuser.
  167.  
  168. The only additional step you may need to take is to create a symbolic
  169. link elsewhere that points at iv/installed.  If you did not change the
  170. definition of InstalledRoot in local.def, then this symbolic link
  171. should have the name "/interviews".  This link allows InterViews
  172. applications to find installed data files at startup time.  For
  173. example, the application "doc" will not be very functional if it
  174. cannot read its menus from /interviews/lib/all/app-defaults/Doc.
  175.  
  176. Once you finish the installation of InterViews, you will no longer
  177. need iv/src (the source tree).  You can say "make clean" to save disk
  178. space by removing all object code files in the source tree.  You can
  179. even copy iv/installed to another computer and use InterViews on that
  180. computer without iv/src having to be present.  If you have a symbolic
  181. link that points at iv/installed, your PATH can be the same on any
  182. computer which contains iv/installed as long as they all have the same
  183. name for the symbolic link (like /interviews).
  184.  
  185.  
  186. * How to use InterViews
  187.  
  188.  
  189. If /interviews is a symbolic link to iv/installed, you can start using
  190. InterViews by putting the following lines in your .cshrc:
  191.  
  192.     setenv CPU SUN4        # or MIPSEL or whatever
  193.     setenv MANPATH $MANPATH:/interviews/man
  194.     setenv PATH $PATH:/interviews/bin/$CPU
  195.  
  196. Once you have /interviews/bin/$CPU in your PATH, you can use the
  197. InterViews script "ivmkmf" to generate Makefiles for your own
  198. InterViews applications.  You have to write an Imakefile first, but
  199. you can do that by copying one of the Imakefiles in iv/src/bin and
  200. replacing the filenames with the names of your application's source
  201. files.  Saying "ivmkmf" will generate a Makefile that contains the
  202. appropriate -I and -L flags for using the InterViews includes and
  203. libraries when building your application.
  204.  
  205.  
  206. * How to write an Imakefile
  207.  
  208.  
  209. The easiest way to write an Imakefile is to start with a copy of a
  210. similar Imakefile and modify it.  If you use only 3.1 classes, you can
  211. copy alert's Imakefile.  If you use both 3.1 and 2.6 classes, you can
  212. copy doc's Imakefile.  If you use only 2.6 classes, you can copy dclock's
  213. Imakefile.  If you use the Unidraw library, you can copy idraw's
  214. Imakefile.  Reading the config files to understand how the rules are
  215. defined will also help if you need to do anything complicated.
  216.  
  217. Some make variables are reserved for your application's use.  You can
  218. compile your application with special compiler flags, defines,
  219. includes, linker flags, or libraries by setting APP_CCFLAGS,
  220. APP_CCDEFINES, APP_CCINCLUDES, APP_CCLDFLAGS, or APP_CCLDLIBS in your
  221. Imakefile.  You can make your application depend on libraries by
  222. setting APP_CCDEPLIBS.
  223.  
  224. You can cause your application to be linked with InterViews libraries
  225. bu using one and only one of the macros Use_libInterViews(),
  226. Use_libUnidraw(), and Use_libgraphic().  Both libUnidraw and
  227. libgraphic depend on libInterViews so saying Use_libUnidraw() or
  228. Use_libgraphic() makes saying Use_libInterViews() unnecessary.  You
  229. cannot say both Use_libUnidraw() and Use_libgraphic() because
  230. libUnidraw and libgraphic conflict with each other.  All of these
  231. macros also add -lXext -lX11 -lm to CCLDLIBS for you.
  232.  
  233. If your application uses classes from the "old" InterViews 2.6,
  234. Unidraw, or graphic libraries, you should use the macro Use_2_6() as
  235. well as one of the macros Use_libInterViews(), Use_libUnidraw(), or
  236. Use_libgraphic().  Many 3.1 classes have the same names as 2.6 classes
  237. so the shorter names are reserved for the 3.1 classes and the 2.6
  238. classes' names are prefixed with "iv2_6_".  The macro Use_2_6() allows
  239. you to use the classes' shorter 2.6 names instead of their real names
  240. and their shorter include paths (<InterViews/*.h>) instead of their
  241. real include paths (<IV-2_6/InterViews/*.h>.  If you want to use
  242. both 3.1 and 2.6 classes in the same application, you will
  243. need to omit Use_2_6() and use the 2.6 classes' real names and
  244. include paths.
  245.  
  246. You can use the macro ComplexProgramTarget(dest) to build a program.
  247. The parameter specifies the name you want the program to have after
  248. it's installed.  The make variable $(AOUT), which defaults to "a.out,"
  249. specifies the name the program will have when it's built.  The make
  250. variable $(OBJS), which defaults to "*.o," specifies the list of
  251. object code files which must be linked together.  You don't have to
  252. define either $(AOUT) or $(OBJS) in the Imakefile because the
  253. generated Makefile will assign default values to them.  You don't have
  254. to define the list of object files in $(OBJS) because the Imakefile
  255. will generate dependencies between the program and its object code
  256. files of the form
  257.  
  258. a.out:
  259.     $(CC) $(OBJS)
  260.  
  261. a.out: a.o
  262. a.out: b.o
  263. a.out: c.o
  264.  
  265. which is equivalent to the traditional form
  266.  
  267. a.out: a.o  b.o  c.o
  268.     $(CC) $(OBJS)
  269.  
  270. You will define these dependencies automatically when you use the
  271. macros MakeObjectFromSrc(file) and MakeObjectFromSrcFlags(file, flags)
  272. for each source file in the program.  Each source file must have its
  273. own rule (hence the macro) because the implicit make rule cannot
  274. compile source files which are not in the current directory.  However,
  275. you won't have to specify the name of the source file again in any
  276. other place in the Imakefile.
  277.  
  278. You should surround the Imakefile with the following lines,
  279.  
  280.     #ifdef InObjectCodeDir
  281.     <contents>
  282.     #else
  283.     MakeInObjectCodeDir()
  284.     #endif
  285.  
  286. so that saying "make Makefiles" will create a subdirectory in which to
  287. put the object code files.  You do not have to use these lines, but if
  288. you do not you will not be able to build optimized, debuggable, and
  289. non-shared object code files alongside of each other in separate
  290. subdirectories.  You also will not be able to build object code files
  291. for different machine architectures alongside of each other in
  292. separate subdirectories.  On the SPARCstation, such object code
  293. directories will have the names SUN4, SUN4.debug, and SUN4.noshared
  294. (the latter two will be created only if you use a special make
  295. command, see below).
  296.  
  297. After you finish writing your Imakefile, saying "ivmkmf" will generate
  298. the corresponding Makefile.  Then you can say "make Makefiles; make
  299. depend; make all" to build your program.  If you make a new change to
  300. the Imakefile, all you have to do is to say "make Makefile"---you
  301. don't have to use "ivmkmf" again.
  302.  
  303. Saying "make Makefiles.debug" and/or "make Makefiles.noshared" will
  304. create the special object code subdirectories and saying "make
  305. depend.debug", "make depend.noshared", "make all.debug", or "make
  306. all.noshared" will build in them just like the normal subdirectories.
  307. Note that the Makefile will provide the "make *.noshared" targets only
  308. if you're on a computer which has shared libraries (currently we
  309. support only SunOS shared libraries).
  310.  
  311. If you write a Makefile by hand instead of writing an Imakefile,
  312. you'll have to specify everything that make needs to know.  For
  313. example, you'll have to specify the -I and -L flags needed to use the
  314. InterViews includes and libraries when compiling your application.
  315. You'll also have to specify any extra flags that your system may need
  316. even though you may have to change them when building on a different
  317. system (when you use an Imakefile, the platform-specific X11 .cf file
  318. specifies these flags for you so they don't have to be in the
  319. Imakefile).
  320.